This document describes the specific functions of the Macintosh version of POV-Ray. It is assumed that you have read (or will read) the POVRAY.DOC file that describes the general operation of POV-Ray. There is also a “POV-Ray 2.0 Notes” file, which contains a change history, source code availability, and advanced tips.
The Persistence of Vision Raytracer creates three-dimensional, photo-realistic images using a rendering technique called ray tracing. It reads in a text file containing information describing the objects and lighting in a scene and generates an image of that scene from the view point of a camera also described in the text file. Ray tracing is not a fast process by any means, but it produces very high quality images with realistic reflections, shading, perspective, and other effects.
Compatibility
-------------
Here are POV-Ray's requirements of hardware and software, and some of its features:
Minimum daily requirements:
68020 CPU or better (e.g., Mac II, IIci, IIfx, LC*, SE/30**, PB180**, Quadras, etc.)
68881 Floating Point Unit or better (or software FPU emulator)
System 6.0.4** or newer (fully System 7 compatible)
Minimum 2 MB RAM for System 6, 4 MB for System 7
32 bit Color QuickDraw required
* NOTE: The Non-FPU version of POV-Ray, although slower,
* will run on any 68020 or better Macintosh (LC, SE, Centris,
* etc.) Otherwise, it has the same requirements as stated
* above, and same features listed below.
Features:
Saves final images as 24-bit PICT files (and Targa files)
Can create animation PICT sequences for making Director or QuickTime movies
Works under both System 6 and System 7 (6.0.4 through 7.1, and beyond?)
Built-in mini text editor with multiple undo, for editing scene files
“Templates” allow instant inserting of any scene elements into file
32 bit clean application (will run in Macs with more than 8MB RAM)
Works with System 7's Virtual Memory
Intelligent support of multiple monitors (dialogs follow the Status Window)
Can run in the background, configurable amount of bkgnd. CPU time stealing
Auto-Shutdown feature, can auto-save and shut down when rendering is done
Handles System 7 Required AppleEvents
Handles System 7 Finder drag-n-drop of multiple source files
Adds System 7 custom Finder icons to rendered PICT files ***
System 7 Balloon Help throughout
Status window contents can be copied to clipboard or saved to text file
Can optionally compress final PICT files ***
(*=only works with additional FPU or software FPU emulator)
(**=only works if "32-Bit QuickDraw" init is installed)
(***=only works if QuickTime 1.5 or newer is installed)
Macintosh Program Notes
-----------------------
User Interface - The implementation of POV-Ray on the Macintosh is quite a leap from the command-line interface of POV-Ray on other platforms. The core code of POV-Ray is identical (including the command line parameter passing), but all of that is hidden from the user, and a more convenient “Graphical User Interface” is provided, with all the menus and dialog boxes you'd expect from a real Macintosh application.
System 6 - If you are using System 6, you will need Apple's "32-Bit QuickDraw" extension installed in your System Folder. This file comes on your System 6.0.7 System disks. Look on the Printing Disk, under the "Apple Color" folder. It should also be available from any authorized Apple Service Center, or CompuServe or local Macintosh bulletin boards. Just drop it into your System Folder and reboot.
Memory Size - Rendering generally uses a LOT of RAM memory to store all the elements of a scene. POV-Ray Mac initially comes with an application memory size set at 2,500 Kilobytes. This size is sufficient to render all of the standard example files (except IONIC5) with room to spare. IONIC5 requires that you set the memory partition to around 5,200K. For less complex images, POV-Ray can render small scenes effectively in a memory partition possibly as small as 800K. The vast majority of the example scene files will render in 1,200K. To change POV's memory size, click once on the POV-Ray program icon from the Finder, then choose “Get Info” from the File menu. The (preferred) application memory size is in a box in the lower right corner of the window, and can be edited. The value is in Kilobytes, so for example, to change it to 6 megabytes (approximately 6,000 Kilobytes,) you would enter 6000.
The Windows - POV-Ray Mac has three windows. The “Status” Window shows progress and statistics during the rendering process. The “Source” Window shows the scene text file to be rendered, and acts as a simple text editor. The “Image” Window is where the final image is generated during rendering. Text from the Status and Source windows can be copied and pasted via the clipboard, and the picture in the Image window can also be copied to the clipboard.
NOTE: When creating a new untitled source file, you must first save it to a disk file before you can set its options or render it.
Output image RAM - POV-Ray tries to store the output image entirely in RAM memory while rendering. Since the image requires approximately Width x Height x 4 bytes of memory, sometimes this is not possible. For example, a 640 x 480 image needs about 1.25 megabytes of RAM. When POV-Ray finds that it can not hold the image in RAM, it will hold it in a temporary disk file, and swap it in to a smaller RAM buffer a few scan-lines at a time. This lets you create very large (4096x4096 theoretically!) images with limited RAM, at the cost of slower rendering time and more disk I/O. This is referred to in POV-Ray Mac as the “Virtual Image Buffer” or VIB. To avoid increased wear and tear on your hard disk, and to speed up rendering times on large images, you can allocate more application memory to POV-Ray instead, to avoid the use of the Virtual Image Buffer. If you do need to use it, you can speed things up by hiding the image window while it renders.
Output image Disk Space - The final images require a fair amount of disk space as well. A final 640x480 PICT image file can take up to 500 KBytes on disk. If you turn on the "Create Targa Output File" option, this separate Targa file can take an additional 1 MByte for a 640x480 image. Keep this in mind so you don't run out of disk space at a critical moment!
VM Delays - If you are using System 7's virtual memory (VM), particularly for extremely complex images, you may notice very large delays during parsing. This is due to the way the memory allocation, the parser and Apple's VM system interact. Once parsing has finished, actual rendering time should be fairly comparable to non-VM systems.
Prefs and VIB files - POV-Ray automatically creates two special types of files during its operation. The first is “POV-Ray Prefs,” which is a small file which will be put inside your System Folder (in the Preferences folder if you use System 7.) It should be left there, as it stores important user settings for POV-Ray. These settings can be changed by choosing the POV-Ray Preferences menu item in the Edit menu. If this file is moved or deleted, POV-Ray will create a new one with default values. One of the things that will need to be reconfigured if this happens is the “Include Paths” settings. The other file is called “POV-Ray.vib,” which is only used during rendering of large images. It is the Virtual Image Buffer file. It is only used while POV-Ray is rendering an image, so if for some reason you notice this large file left behind after POV-Ray quits, it is OK - and suggested - that you delete it.
Where do I start?
-----------------
(1) INSTALL
Decide where to put POV-Ray and its associated files. There are no restrictions on where the files can go, but you may want to create a “POV-Ray” folder and keep things together. The archives are "self-extracting", which means that you merely double-click an archive file, and it will prompt you for a disk and folder to save its files onto, and then it will expand and copy the files there.
The following table will give you an idea of how much free hard disk space you will need for expanding the archives:
Archive -- Expands to about
----------- ---------------
POVDOC.SEA 650 KBytes
POVMAC.SEA 500 KBytes
POVMNF.SEA 670 KBytes
POVSCN.SEA 1.2 MBytes
POVSRC.SEA 2.2 MBytes
So, as a bare minimum, the POV-Ray application folder (500 KB) and the Documentation folder (650 KB) use approximately 1.2 MBytes of disk space. And although it is big, you will find the Sample Scenes archive (POVSCN) full of examples on how to do things.
First decide which application you need for your Macintosh... do you have a floating point unit (FPU) installed? If so, get the regular POVMAC.SEA archive, otherwise get the POVMNF.SEA archive. Now extract the POV-Ray application from the POVMAC (or POVMNF) archive. Then get and extract the documentation and demo and include folders from the POVDOC archive. It would be a good idea to do a quick browse of the first part of the POVRAY.DOC manual now, before going too much farther.
(2) CONFIGURE
Determine how much RAM memory you have in your Macintosh, and how much you should set POV-Ray to (see Memory Size above.) Set the POV-Ray application memory size appropriately.
(3) INSTALL SOME MORE
In step (1), you extracted the folder :INCLUDE: from the POVDOC archive, and saved it somewhere on your Macintosh. This folder has include files with many predefined colors, textures, and shapes that you can immediately use (it is required if you are going to render any of the demo or example scene files.)
NOTE: After extracting INCLUDE, you may want to rename this generic folder name to something like “POV.Includes”. Various books and documentation for POV-Ray refer to this standard include folder as "INCLUDE"; So if you do rename it, you need to mentally make the connection to the original name, in case you run across references to "INCLUDE" in other documents.
You must now tell POV-Ray where that INCLUDE folder is. This is done by running POV-Ray and selecting POV-Ray Preferences from the Edit menu. At the bottom of the dialog is a button called "Set Include Folder…". Click this button, and use the Standard File dialog to find and select any one of the include files inside your INCLUDE folder.
This folder is remembered from now on in POV-Ray's preferences file, so you don't have to keep finding it. Later you may want to create a library of your own include files. You can add these files to this folder, and they will always be found. This folder is automatically scanned for files when POV-Ray encounters an “#include” command, along with the current folder (the one with your scene file in it.)
(4) DOUBLE-CLICK - You are now ready to run POV-Ray.
To render an existing source file, like one of the demo or sample files, do the following:
<4a> Double-click POV-Ray and use “Open” from the File menu to open the scene file. Under System 7, you can also drag the source file over and drop it onto the POV-Ray application. This will run POV-Ray and automatically open the source file. Note that the POV-Ray editor can only open ONE source file at a time. If you drop multiple files onto POV-Ray, it will start automatically rendering each file and saving each image to a separate image file. This is another great feature in itself, but probably not what you wanted to do just yet! This “batch-rendering” feature is covered in the file "POV-Ray 2.0 Notes", under Advanced Tips.
<4b> Choose “Rendering Options” from the Render menu, and fill out the dialog with the options you want (see POVRAY.DOC or use System 7 Balloon Help for more information on these.) For now, you may want to choose the “32x32” or “64x64” image presets from the popup menu, to pick a small, quick render.
<4c> Choose the “View” - “Normal” item from the “Image” menu, so the output image is shown as it renders.
<4d> Choose “Render” from the Render menu, and POV-Ray will read and “parse” the source file, and then create an output image.
<4e> When it completes, you may copy the image to the clipboard. Make sure the image window is in front, and select “Copy” from the Edit menu. You can also save the image as a PICT file, by choosing “Save” or “Save As” from the File menu.
##### or, for the more adventurous ######
(5) CREATE A NEW SCENE FILE
To create a new source file of your own, just double-click POV-Ray, or choose “New” from POV-Ray's File menu if it is already running. You are presented with an “Untitled.POV” Source window, and the Status window. You would then do the following to create and render a new file:
<5a> Type some POV-Ray source statements into the Source window. A very useful built-in aid for automating this is an item hiding under the Edit menu, “Insert Template”. This hierarchical menu contains syntactically correct ready-to-use text for every POV-Ray statement. You just choose one (camera, light_source, texture, sphere, etc.) and it will insert it right into your source file wherever your cursor is. You just edit the parameters after that to tailor it.
<5b> Save the file to disk (choose “Save” under the File menu). Note that the renderer expects the file to be saved to disk, and you cannot set the rendering options or start rendering until you do this.
<5c> Choose “Rendering Options” from the Render menu, and fill out the dialog with the options you want. See the "Rendering Options" section of the POV-Ray 2.0 Notes document for more information on this dialog.
<5d> Choose the “View” - “Normal Size” item from the Image menu.
<5e> Now choose “Render” from the Render menu, and your source file will be read and “parsed”, and if there were no errors, an output image will start to be generated.
<5f> If POV-Ray finds an error in your source file, it will display an error dialog, write a description of the error to the Status window, and automatically select the source line in error, for you to fix. You can fix the line, save the updated file to disk (press command-S), and re-render the scene.
Other Files
-----------
In addition to the application, you should also find other POV-Ray archives with the following contents:
POVDOC.SEA - POV-Ray Documentation, essential include files and demo scenes
POVSCN.SEA - Many great example Scene Files
POVSRC.SEA - Think C and MPW C compatible Macintosh Source Code for POV-Ray
Credits and Blame
-----------------
This Mac front end has a long and sordid history... I will tell you what I know.
Eduard Schwan created 2.0 by extensively modifying Jim Nitchals' 1.0 version, which was an extensive modification of an earlier version written by Thomas Okken. A few other ideas were gleaned from an even earlier Macintosh version built by Glenn Sugden. Things get awfully fuzzy and primordial before that.
Dave Harr did the original 1.0 Balloon Help, helped design some user interface changes, and added the custom palette code.
Jim Nitchals added the mini text editor with multiple undo, and invented the virtual image buffer swapping code, and the first version of the PICT file saving package. Jim also improved the POV-Ray multitasking and memory management (COOPERATE and POV_Malloc) to allow multiple renderings without having to quit the program between renders. He also synthed up the “Done” boing sound.
Eduard [esp] Schwan ported the code from Think C 5 and built and tested it in MPW C, revamped the user interface one more time (and had to continually rewrite Balloon Help to match), invented some code for a generic status window that captured “printf”s for both Think and MPW, got the AppleEvent stuff to work, worked on the memory management, added QuickTime Image Compression, rewrote the prefs code, added multi-file drag-n-drop, added the Mac animation support, retested and rebuilt the Think C 6 version, re-worded this document, and bombarded Jim and other team members with late night calls, bug reports, source changes, and wild suggestions.
Anton Raves relentlessly put the Beta POV-Ray 2.0 through its paces, and found all sorts of “unexpected features” in the program. Many thanks for his tireless efforts, great suggestions, and imperceptible Dutch accent!
Mark de Jong complained about all sorts of documentation and user interface abominations in the Beta 2.0 version, and really kept me on my toes.
Jim would like to thank his wonderful wife and best friend, Cindy, for her support while he was coding and rendering many late nights. Thanks!
Eduard would like to thank Lorrie, Bryon, Sara, Sushi, and V.G.s (patient wife, impatient 5 year old son, brand-new daughter, oblivious lap cat, and super donut shop) for sticking around while the bugs and pixels were thickest.
Jim wishes there was a VG.'s nearby. They DO make the best donuts and also baked Cindy's and his wedding cake.
Encore... more info please!
---------------------------
(1) Refer to the POV-Ray documentation for general information on the scene description language, and general theory of operation. This is contained in the included POVDOC archive.
(2) For a superb in-depth discussion of the POV-Ray raytracer (version 1.0), you should get a copy of the book, "Ray Tracing Creations", by Drew Wells, published by the Waite Group Press, ISBN 1-878739-27-1. It is written for the 1.0 MSDOS version of the program, but very little of the book dwells on MSDOS specifics, most of the book talks about the scene description language, and how the raytracer works in general. Another book that briefly discusses POV-Ray 1.0 is "Image Lab", by Tim Wegner, also published by the Waite Group Press, ISBN 1-878739-11-5.
(3) For on-line information, new files, and technical support, join Compuserve's Graphics Developers forum (GRAPHDEV), or America Online's Company Support area of the PC Graphics Forum (keyword: "PGR").
(4) There are many utility programs out there that convert files to POV-Ray format or create POV-Ray objects. A handful of these utilities was ported to the Macintosh, and is on Compuserve and America OnLine as the "Macintosh POV-Utilities", ported by Eduard [esp] Schwan. These are worth checking out.
(5) For Macintosh-specific issues, please feel free to contact one of us directly:
Eduard [esp] Schwan can be reached on:
Compuserve: 71513,2161
AppleLink: JL.Tech
Internet: 71513.2161@compuserve.com or jl.tech@applelink.apple.com
(I will be checking Compuserve every day or so. I check AppleLink every day, but it is my company's account, so it should not be overused. The Internet accounts are, as you can tell, simply gateways to my Applelink or CIS accounts. The CIS account is preferred.)
Jim Nitchals can be reached on:
America Online: JimN8
Compuserve: 73117,3020
Applelink: JimN8
Internet: jimn8@applelink.apple.com or jimn8@aol.com
(AppleLink is now the preferred method of contacting me, but I check AOL and CIS often too. For Internet, please use my AppleLink address and NOT my AOL or Compuserve address unless you have problems with the AppleLink mail gateway.)
Note: When sending us questions via e-mail, we would like to assume that your question can be re-posted publicly in other online forums along with the reply. This way others can benefit from your experience. If you don't want your question posted publicly, no problem, just let us know.
